---
title: 페이지
description: Astro 페이지 소개
i18nReady: true
---
import ReadMore from '~/components/ReadMore.astro';
import Since from '~/components/Since.astro'

**페이지**는 Astro 프로젝트의 `src/pages/` 하위 디렉터리에 있는 파일입니다. 웹 사이트의 모든 페이지에 대한 라우팅, 데이터 로딩 및 전체 페이지 레이아웃을 처리합니다.

## 지원되는 페이지 파일

Astro는 `src/pages/` 디렉터리에서 다음 파일 형식을 지원합니다.

- [`.astro`](#astro-페이지)
- [`.md`](#markdownmdx-페이지)
- `.mdx` ([MDX 통합 설치 시](/ko/guides/integrations-guide/mdx/#설치))
- [`.html`](#html-페이지)
- `.js`/`.ts` ([엔드포인트](/ko/guides/endpoints/)로 사용 시)

## 파일 기반 라우팅

Astro는 **파일 기반 라우팅**이라는 라우팅 전략을 활용합니다. `src/pages/` 디렉터리의 각 파일은 파일 경로를 기반으로 사이트의 엔드포인트가 됩니다.

단일 파일은 [동적 라우팅](/ko/guides/routing/#동적-라우트)을 사용하여 여러 페이지를 생성할 수도 있습니다. 이를 통해 [콘텐츠 컬렉션](/ko/guides/content-collections/)이나 [CMS](/ko/guides/cms/)와 같이, 특수 `/pages/` 디렉터리 외부에 콘텐츠가 있는 경우에도 페이지를 만들 수 있습니다.

<ReadMore>[Astro의 라우팅](/ko/guides/routing/)에 대해 자세히 알아보세요.</ReadMore>

### 페이지 간 링크

Astro 페이지에서 표준 HTML [`<a>` 요소](https://developer.mozilla.org/ko/docs/Web/HTML/Element/a)를 작성하여 사이트의 다른 페이지에 연결합니다. 상대 파일 경로가 아닌 **루트 도메인에 상대적인 URL 경로**를 링크로 사용하세요.

예를 들어, `example.com`의 다른 페이지에서 `https://example.com/authors/sonali/`로 연결하려면 다음을 따릅니다.

```astro title="src/pages/index.astro"
<a href="/authors/sonali/">Sonali</a>에 대해 더 자세히 알아보세요.
```

## Astro 페이지

Astro 페이지는 `.astro` 파일 확장자를 사용하며 [Astro 컴포넌트](/ko/basics/astro-components/)와 동일한 기능을 지원합니다.

```astro title="src/pages/index.astro"
---
---
<html lang="ko-KR">
  <head>
    <title>나의 홈페이지</title>
  </head>
  <body>
    <h1>나의 웹사이트에 오신 것을 환영합니다!</h1>
  </body>
</html>
```

페이지는 전체 HTML 문서를 생성해야 합니다. 명시적으로 포함되지 않은 경우 Astro는 기본적으로 `src/pages/`에 있는 모든 `.astro` 컴포넌트에 `<!DOCTYPE html>` 선언과 `<head>` 콘텐츠를 추가합니다. [부분](#페이지-부분-page-partials) 페이지로 표시하여 컴포넌트별로 이 동작을 선택 해제할 수 있습니다.

모든 페이지에서 동일한 HTML 요소를 반복하는 것을 방지하려면 공통 `<head>` 및 `<body>` 요소를 사용자 정의 [레이아웃 컴포넌트](/ko/basics/layouts/)로 이동하면 됩니다. 원하는 만큼 레이아웃 컴포넌트를 사용할 수 있습니다.

```astro title="src/pages/index.astro" /</?MySiteLayout>/ {2}
---
import MySiteLayout from "../layouts/MySiteLayout.astro";
---
<MySiteLayout>
  <p>레이아웃으로 래핑된 페이지 콘텐츠입니다!</p>
</MySiteLayout>
```

<ReadMore>Astro의 [레이아웃 컴포넌트](/ko/basics/layouts/)에 대해 자세히 알아보세요.</ReadMore>

## Markdown/MDX 페이지

Astro는 `src/pages/`의 모든 Markdown (`.md`) 파일을 최종 웹 사이트의 페이지로 처리합니다. [MDX 통합이 설치](/ko/guides/integrations-guide/mdx/#설치)되어 있는 경우 MDX (`.mdx`) 파일도 같은 방식으로 처리합니다.

:::tip
블로그 게시물이나 제품 항목과 같이 유사한 구조를 공유하는 Markdown 파일의 디렉터리에 대해서는 페이지 대신 [콘텐츠 컬렉션](/ko/guides/content-collections/) 생성을 고려하세요.
:::

Markdown 파일은 특수 `layout` 프런트매터 속성을 사용하여 Markdown 콘텐츠를 전체 `<html>...</html>` 페이지 문서로 래핑하는 [레이아웃 컴포넌트](/ko/basics/layouts/)를 지정할 수 있습니다.

```md title="src/pages/page.md" {2}
---
layout: ../layouts/MySiteLayout.astro
title: 나의 Markdown 페이지
---
# 제목

**Markdown**으로 작성된 페이지입니다.
```

<ReadMore>Astro의 [Markdown](/ko/guides/markdown-content/)에 대해 자세히 알아보세요.</ReadMore>

## HTML 페이지

`.html` 파일 확장자를 가진 파일은 `src/pages/` 디렉터리에 배치하여 사이트에서 페이지로 직접 사용할 수 있습니다. 일부 주요 Astro 기능은 [HTML 컴포넌트](/ko/basics/astro-components/#html-컴포넌트)에서 지원되지 않습니다.

## 사용자 정의 404 오류 페이지

사용자 정의 404 오류 페이지를 만들려면 `src/pages`에 `404.astro` 또는 `404.md` 파일을 생성하면 됩니다.

그러면 `404.html` 페이지로 빌드됩니다. 대부분의 [배포 서비스](/ko/guides/deploy/)는 이 페이지를 찾아 사용합니다.

## 사용자 정의 500 오류 페이지

[요청 시 렌더링](/ko/guides/on-demand-rendering/)되는 페이지에 표시할 사용자 정의 500 오류 페이지를 만들려면 `src/pages/500.astro` 파일을 생성하세요. 이 사용자 정의 페이지는 사전 렌더링된 페이지에서는 사용할 수 없습니다.

이 페이지를 렌더링하는 동안 오류가 발생하면 호스트의 기본 500 오류 페이지가 방문자에게 표시됩니다.

<p><Since v="4.10.3" /></p>

개발 중에 `500.astro`가 있는 경우, 런타임에 발생하는 오류는 오류 오버레이에 표시되는 대신 터미널에 기록됩니다.

### `error`

<p><Since v="4.11.0" /></p>

`src/pages/500.astro`는 렌더링 중에 발생하는 모든 오류에 대해 자동으로 `error` prop이 전달되는 특수 페이지입니다. 이를 통해 오류 세부 정보 (예: 페이지 오류, 미들웨어 오류 등)를 사용하여 방문자에게 정보를 표시할 수 있습니다.

`error` prop의 데이터 타입은 어떤 것이든 될 수 있으며, 이는 코드에서 타입을 지정하거나 값을 사용하는 방식에 영향을 줄 수 있습니다.

```astro title="src/pages/500.astro"
---
interface Props {
  error: unknown;
}

const { error } = Astro.props;
---
<div>{error instanceof Error ? error.message : "알 수 없는 오류"}</div>
```

`error` prop의 콘텐츠를 표시할 때 중요한 정보가 유출되는 것을 방지하려면 먼저 오류를 평가하고 발생한 오류에 따라 적절한 콘텐츠를 반환하는 것을 고려하세요. 예를 들어, 오류의 스택은 서버의 코드 구조에 대한 정보를 포함하므로 표시하지 않아야 합니다.

## 페이지 부분 (Page Partials)

<p><Since v="3.4.0" /></p>

:::caution
페이지 부분은 [htmx](https://htmx.org/) 또는 [Unpoly](https://unpoly.com/)와 같은 프런트엔드 라이브러리와 함께 사용하기 위한 용도입니다. 로우 레벨 프런트엔드 JavaScript를 작성하는 데 능숙하다면 사용할 수도 있습니다. 이러한 이유로 고급 기능입니다.

또한, 부분 (partials)은 컴포넌트에 범위가 지정된 스타일 또는 스크립트가 포함된 경우 사용하면 안 됩니다. 이러한 요소는 HTML 출력에서 제거되기 때문입니다. 범위가 지정된 스타일이 필요한 경우, 콘텐츠를 헤드에 병합하는 방법을 알고 있는 프런트엔드 라이브러리와 함께 일반적인 비부분 (non-partial) 페이지를 사용하는 것이 좋습니다.
:::

부분은 전체 페이지로 렌더링되지 않는 `src/pages/`에 위치한 페이지 컴포넌트입니다.

이 폴더 외부에 있는 컴포넌트와 마찬가지로 이러한 파일에는 `<!DOCTYPE html>` 선언이나 범위가 지정된 스타일 및 스크립트와 같은 `<head>` 콘텐츠가 자동으로 포함되지 않습니다.

하지만 특수 `src/pages/` 디렉터리에 있기 때문에 생성된 HTML은 파일 경로에 해당하는 URL에서 사용할 수 있습니다. 따라서 렌더링 라이브러리 (예: [htmx](https://htmx.org/), [Stimulus](https://stimulus.hotwired.dev/), [jQuery](https://jquery.com/))는 클라이언트에서 액세스하여 브라우저 새로 고침이나 페이지 탐색 없이 페이지에서 HTML 섹션을 동적으로 로드할 수 있습니다.

부분은 렌더링 라이브러리와 결합하면 Astro에서 동적 콘텐츠를 구축하기 위한 [Astro 아일랜드](/ko/concepts/islands/) 및 [`<script>` 태그](/ko/guides/client-side-scripts/)의 대안을 제공합니다.

[`partial`](/ko/reference/routing-reference/#partial) 값을 내보낼 수 있는 페이지 파일 (`.astro` 및 `.mdx`는 가능하지만 `.md`는 불가능)은 부분으로 표시될 수 있습니다.

```astro title="src/pages/partial.astro" ins={2}
---
export const partial = true;
---
<li>여기는 부분 (partial)입니다!</li>
```

### 라이브러리와 함께 사용

부분은 [htmx](https://htmx.org/)와 같은 라이브러리를 사용하여 페이지의 섹션을 동적으로 업데이트하는 데 사용됩니다.

다음 예제는 부분의 URL로 설정된 `hx-post` 속성을 보여줍니다. 부분 페이지의 콘텐츠는 이 페이지의 대상 HTML 요소를 업데이트하는 데 사용됩니다.

```astro title="src/pages/index.astro" 'hx-post="/partials/clicked/"'
<html>
  <head>
    <title>나의 페이지</title>
    <script src="https://unpkg.com/htmx.org@1.9.6"
      integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
      crossorigin="anonymous"></script>
  </head>
  <body>
    <section>
      <div id="parent-div">대상 요소</div>
    
      <button hx-post="/partials/clicked/"
        hx-trigger="click"
        hx-target="#parent-div"
        hx-swap="innerHTML"
      >
        여기를 클릭하세요!
      </button>
    </section>
  </body>
</html>
```

해당 파일 경로에 `.astro` 부분이 존재해야 하며, 페이지를 부분으로 정의하는 내보내기를 포함해야 합니다.

```astro title="src/pages/partials/clicked.astro" {2}
---
export const partial = true;
---
<div>클릭하였습니다!</div>
```

htmx 사용에 대한 자세한 내용은 [htmx 문서](https://htmx.org/docs/)를 참조하세요.
